vergen

Current Release

Build Status

Travis
GitLab CI/CD
Appveyor

Code Coverage

Version 3.x.x

Introduces generate_cargo_keys() and support for rebuild when .git/HEAD changes. Internally converted to use failure so Result is no longer exported and changed to the Rust 2018 edition.

This means the 3.x.x version will only work in the beta and nightly channels until Rust 2018 hits stable (12/06/18)

Version 2.1.x

Backport of the 3.x.x changes to work on stable until Rust 2018 hits stable.

Version 2.0.x

Compatible with Version 1.x.x, but introduces a completely new way to use the constants without having to use the include! macro.

Documentation

Documentation

Generate Compile Time Information

vergen, when used in conjunction with cargo build scripts, will generate environment variables to use with the env! macro. Below is a list of the supported variables.

The variable generation can be toggled on or off at an individual level via ConstantsFlags

Note on SEMVER

VERGEN_SEMVER can be generated via git describe or by env::var("CARGO_PKG_VERSION").

By default, SEMVER uses git describe if possible, and falls back to CARGO_PKG_VERSION.

If you wish to force CARGO_PKG_VERSION, toggle off SEMVER and toggle on SEMVER_FROM_CARGO_PKG.

Re-build On Changed HEAD

vergen can also be configured to re-run build.rs when either .git/HEAD or the file that .git/HEAD points at changes.

This can behavior can be toggled on or of with the REBUILD_ON_HEAD_CHANGE flag.

'cargo:' Key Build Script Output

[package]
#..
build = "build.rs"

[dependencies]
#..

[build-dependencies]
vergen = "3"

Example 'build.rs'

extern crate vergen;

use vergen::{ConstantsFlags, generate_cargo_keys};

fn main() {
    // Setup the flags, toggling off the 'SEMVER_FROM_CARGO_PKG' flag
    let mut flags = ConstantsFlags::all();
    flags.toggle(ConstantsFlags::SEMVER_FROM_CARGO_PKG);

    // Generate the 'cargo:' key output
    generate_cargo_keys(ConstantsFlags::all()).expect("Unable to generate the cargo keys!");
}

Use the constants in your code

fn my_fn() {
    println!("Build Timestamp: {}", env!("VERGEN_BUILD_TIMESTAMP"));
}

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT) at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.